home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 October: Mac OS SDK / Dev.CD Oct 97 SDK1.toast / Development Kits (Disc 1) / Interfaces&Libraries / Universal / Interfaces / CIncludes / OSA.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-08-12  |  54.5 KB  |  1,728 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        OSA.h
  3.  
  4.      Contains:    AppleScript Client Interfaces.
  5.  
  6.      Version:    Technology:    AppleScript 1.1
  7.                  Release:    Universal Interfaces 3.0.1
  8.  
  9.      Copyright:    © 1992-1997 by Apple Computer, Inc., all rights reserved
  10.  
  11.      Bugs?:        Please include the the file and version information (from above) with
  12.                  the problem description.  Developers belonging to one of the Apple
  13.                  developer programs can submit bug reports to:
  14.  
  15.                      devsupport@apple.com
  16.  
  17. */
  18. #ifndef __OSA__
  19. #define __OSA__
  20.  
  21. #ifndef __ERRORS__
  22. #include <Errors.h>
  23. #endif
  24. #ifndef __APPLEEVENTS__
  25. #include <AppleEvents.h>
  26. #endif
  27. #ifndef __AEOBJECTS__
  28. #include <AEObjects.h>
  29. #endif
  30. #ifndef __COMPONENTS__
  31. #include <Components.h>
  32. #endif
  33.  
  34.  
  35.  
  36. #if PRAGMA_ONCE
  37. #pragma once
  38. #endif
  39.  
  40. #ifdef __cplusplus
  41. extern "C" {
  42. #endif
  43.  
  44. #if PRAGMA_IMPORT
  45. #pragma import on
  46. #endif
  47.  
  48. #if PRAGMA_STRUCT_ALIGN
  49.     #pragma options align=mac68k
  50. #elif PRAGMA_STRUCT_PACKPUSH
  51.     #pragma pack(push, 2)
  52. #elif PRAGMA_STRUCT_PACK
  53.     #pragma pack(2)
  54. #endif
  55.  
  56. /**************************************************************************
  57.     Types and Constants
  58. **************************************************************************/
  59.  
  60. /*    The componenent manager type code for components that
  61.         support the OSA interface defined here. */
  62. /* 0x6f736120 */
  63.  
  64. enum {
  65.     kOSAComponentType            = FOUR_CHAR_CODE('osa ')
  66. };
  67.  
  68. /* 0x73637074 */
  69.  
  70. enum {
  71.     kOSAGenericScriptingComponentSubtype = FOUR_CHAR_CODE('scpt')
  72. };
  73.  
  74. /*    Type of script document files.    */
  75. /* 0x6f736173 */
  76.  
  77. enum {
  78.     kOSAFileType                = FOUR_CHAR_CODE('osas')
  79. };
  80.  
  81. /*
  82.         Suite and event code of the RecordedText event. 
  83.         (See OSAStartRecording, below.)
  84.     */
  85. /* 0x61736372 */
  86.  
  87. enum {
  88.     kOSASuite                    = FOUR_CHAR_CODE('ascr')
  89. };
  90.  
  91. /* 0x72656364 */
  92.  
  93. enum {
  94.     kOSARecordedText            = FOUR_CHAR_CODE('recd')
  95. };
  96.  
  97. /* Selector returns boolean */
  98. /* 0x6d6f6469 */
  99.  
  100. enum {
  101.     kOSAScriptIsModified        = FOUR_CHAR_CODE('modi')
  102. };
  103.  
  104. /* Selector returns boolean */
  105. /* 0x63736372 */
  106.  
  107. enum {
  108.     kOSAScriptIsTypeCompiledScript = FOUR_CHAR_CODE('cscr')
  109. };
  110.  
  111. /* Selector returns boolean */
  112. /* 0x76616c75 */
  113.  
  114. enum {
  115.     kOSAScriptIsTypeScriptValue    = FOUR_CHAR_CODE('valu')
  116. };
  117.  
  118. /* Selector returns boolean */
  119. /* 0x636e7478 */
  120.  
  121. enum {
  122.     kOSAScriptIsTypeScriptContext = FOUR_CHAR_CODE('cntx')
  123. };
  124.  
  125. /* Selector returns a DescType which may be passed to OSACoerceToDesc */
  126. /* 0x62657374 */
  127.  
  128. enum {
  129.     kOSAScriptBestType            = FOUR_CHAR_CODE('best')
  130. };
  131.  
  132. /*
  133.         This selector is used to determine whether a script has source 
  134.         associated with it that when given to OSAGetSource, the call will not
  135.         fail.  The selector returns a boolean.
  136.     */
  137. /* 0x67737263 */
  138.  
  139. enum {
  140.     kOSACanGetSource            = FOUR_CHAR_CODE('gsrc')
  141. };
  142.  
  143.  
  144.  
  145. enum {
  146.     typeOSADialectInfo            = FOUR_CHAR_CODE('difo'),        /*  0x6469666f   */
  147.     keyOSADialectName            = FOUR_CHAR_CODE('dnam'),        /*  0x646e616d   */
  148.     keyOSADialectCode            = FOUR_CHAR_CODE('dcod'),        /*  0x64636f64   */
  149.     keyOSADialectLangCode        = FOUR_CHAR_CODE('dlcd'),        /*  0x646c6364   */
  150.     keyOSADialectScriptCode        = FOUR_CHAR_CODE('dscd')        /*  0x64736364   */
  151. };
  152.  
  153. typedef ComponentResult                 OSAError;
  154. /* Under the Open Scripting Architecture all error results are longs */
  155. typedef unsigned long                     OSAID;
  156. /*
  157.         OSAIDs allow transparent manipulation of scripts associated with
  158.          various scripting systems.
  159.     */
  160.  
  161. enum {
  162.     kOSANullScript                = 0L
  163. };
  164.  
  165. /* No -script constant. */
  166.  
  167. enum {
  168.     kOSANullMode                = 0,                            /* sounds better */
  169.     kOSAModeNull                = 0                                /* tastes consistent */
  170. };
  171.  
  172. /*
  173.         Some routines take flags that control their execution.  This constant
  174.         declares default mode settings are used.
  175.     */
  176. typedef CALLBACK_API( OSErr , OSACreateAppleEventProcPtr )(AEEventClass theAEEventClass, AEEventID theAEEventID, const AEAddressDesc *target, short returnID, long transactionID, AppleEvent *result, long refCon);
  177. typedef CALLBACK_API( OSErr , OSASendProcPtr )(const AppleEvent *theAppleEvent, AppleEvent *reply, AESendMode sendMode, AESendPriority sendPriority, long timeOutInTicks, AEIdleUPP idleProc, AEFilterUPP filterProc, long refCon);
  178. typedef STACK_UPP_TYPE(OSACreateAppleEventProcPtr)                 OSACreateAppleEventUPP;
  179. typedef STACK_UPP_TYPE(OSASendProcPtr)                             OSASendUPP;
  180. enum { uppOSACreateAppleEventProcInfo = 0x000FEFE0 };             /* pascal 2_bytes Func(4_bytes, 4_bytes, 4_bytes, 2_bytes, 4_bytes, 4_bytes, 4_bytes) */
  181. enum { uppOSASendProcInfo = 0x003FEFE0 };                         /* pascal 2_bytes Func(4_bytes, 4_bytes, 4_bytes, 2_bytes, 4_bytes, 4_bytes, 4_bytes, 4_bytes) */
  182. #define NewOSACreateAppleEventProc(userRoutine)                 (OSACreateAppleEventUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppOSACreateAppleEventProcInfo, GetCurrentArchitecture())
  183. #define NewOSASendProc(userRoutine)                             (OSASendUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppOSASendProcInfo, GetCurrentArchitecture())
  184. #define CallOSACreateAppleEventProc(userRoutine, theAEEventClass, theAEEventID, target, returnID, transactionID, result, refCon)  CALL_SEVEN_PARAMETER_UPP((userRoutine), uppOSACreateAppleEventProcInfo, (theAEEventClass), (theAEEventID), (target), (returnID), (transactionID), (result), (refCon))
  185. #define CallOSASendProc(userRoutine, theAppleEvent, reply, sendMode, sendPriority, timeOutInTicks, idleProc, filterProc, refCon)  CALL_EIGHT_PARAMETER_UPP((userRoutine), uppOSASendProcInfo, (theAppleEvent), (reply), (sendMode), (sendPriority), (timeOutInTicks), (idleProc), (filterProc), (refCon))
  186. /**************************************************************************
  187.     Standard Script Errors
  188. **************************************************************************
  189.     It is recommended that scripting components use the following set of error
  190.     codes to signal failure when applicable.  This enables applications that
  191.     use the OSA API to deal with some class of script errors in a less than 
  192.     ad hoc manner.  Scripting components are of course encouraged to return
  193.     component-specific errors when these don't apply.
  194. **************************************************************************/
  195. /*        Dynamic errors:
  196.  
  197.     These errors result from data-dependent conditions and are typically
  198.     signaled at runtime.
  199. */
  200. /*
  201.         Signaled when a value can't be coerced to the desired type. Similar
  202.           to errOSATypeError except results from coercion.
  203.     */
  204.  
  205. enum {
  206.     errOSACantCoerce            = errAECoercionFail
  207. };
  208.  
  209. /* Signaled when an object is not found in a container */
  210.  
  211. enum {
  212.     errOSACantAccess            = errAENoSuchObject
  213. };
  214.  
  215. /*
  216.         Signaled when an object cannot be set in a container.  Same as 
  217.           AERegistry error errAEWriteDenied.
  218.     */
  219.  
  220. enum {
  221.     errOSACantAssign            = -10006
  222. };
  223.  
  224. /*
  225.         Signaled by user scripts or applications when no actual error code
  226.           is to be returned.  Simply means "an error has occurred".  Most useful
  227.           in conjunction with an error message from the application.
  228.     */
  229.  
  230. enum {
  231.     errOSAGeneralError            = -2700
  232. };
  233.  
  234. /* Signaled when there is an attempt to divide by zero */
  235.  
  236. enum {
  237.     errOSADivideByZero            = -2701
  238. };
  239.  
  240. /* Signaled when integer or real value is too large to be represented */
  241.  
  242. enum {
  243.     errOSANumericOverflow        = -2702
  244. };
  245.  
  246. /*
  247.         Signaled when application can't be launched or when it is remote and
  248.           program linking is not enabled.
  249.     */
  250.  
  251. enum {
  252.     errOSACantLaunch            = -2703
  253. };
  254.  
  255. /* Signaled when an application can't respond to AppleEvents */
  256.  
  257. enum {
  258.     errOSAAppNotHighLevelEventAware = -2704
  259. };
  260.  
  261. /* Signaled when an application's terminology resource is not readable */
  262.  
  263. enum {
  264.     errOSACorruptTerminology    = -2705
  265. };
  266.  
  267. /* Signaled when the runtime stack overflows */
  268.  
  269. enum {
  270.     errOSAStackOverflow            = -2706
  271. };
  272.  
  273. /* Signaled when a runtime internal data structure overflows */
  274.  
  275. enum {
  276.     errOSAInternalTableOverflow    = -2707
  277. };
  278.  
  279. /*
  280.         Signaled when an intrinsic limitation is exceeded for the size of 
  281.           a value or data structure.
  282.     */
  283.  
  284. enum {
  285.     errOSADataBlockTooLarge        = -2708
  286. };
  287.  
  288.  
  289. enum {
  290.     errOSACantGetTerminology    = -2709
  291. };
  292.  
  293.  
  294. enum {
  295.     errOSACantCreate            = -2710
  296. };
  297.  
  298. /*        Component-specific dynamic script errors:
  299.  
  300.     The range -2720 thru -2739 is reserved for component-specific runtime errors.
  301.     (Note that error codes from different scripting components in this range will
  302.     overlap.)
  303. */
  304. /*        Static errors:
  305.  
  306.     These errors comprise what are commonly thought of as parse and compile-
  307.     time errors.  However, in a dynamic system (e.g. AppleScript) any or all
  308.     of these may also occur at runtime.
  309. */
  310.  
  311. /* Signaled when data was not the right type and coercion is not allowed */
  312.  
  313. enum {
  314.     errOSATypeError                = errAEWrongDataType
  315. };
  316.  
  317. /* Signaled when a message was sent to an object that didn't handle it */
  318.  
  319. enum {
  320.     OSAMessageNotUnderstood        = errAEEventNotHandled
  321. };
  322.  
  323. /*
  324.         Signaled when a function to be returned doesn't exist.  (Probably only
  325.           useful in languages with first-class functions that distinguish between
  326.           functions and other values (two name spaces). This is different from
  327.           errOSAMessageNotUnderstood, which may be signaled when the method is
  328.           invoked.
  329.     */
  330.  
  331. enum {
  332.     OSAUndefinedHandler            = errAEHandlerNotFound
  333. };
  334.  
  335. /* Signaled when a container can never have the requested object */
  336.  
  337. enum {
  338.     OSAIllegalAccess            = errAEAccessorNotFound
  339. };
  340.  
  341. /* Signaled when index was out of range. Specialization of errOSACantAccess. */
  342.  
  343. enum {
  344.     OSAIllegalIndex                = errAEIllegalIndex
  345. };
  346.  
  347. /* Signaled when a range is screwy. Specialization of errOSACantAccess. */
  348.  
  349. enum {
  350.     OSAIllegalRange                = errAEImpossibleRange
  351. };
  352.  
  353. /*
  354.         Signaled when an object can never be set in a container.  Same as 
  355.           AERegistry error errAENotModifiable.
  356.     */
  357.  
  358. enum {
  359.     OSAIllegalAssign            = -10003
  360. };
  361.  
  362. /*
  363.         Signaled when a syntax error occurs. (e.g. "Syntax error" or
  364.          "<this> can't go after <that>").
  365.     */
  366.  
  367. enum {
  368.     OSASyntaxError                = -2740
  369. };
  370.  
  371. /*
  372.         Signaled when another form of syntax was expected. (e.g. "expected
  373.           a <type> but found <this>").
  374.     */
  375.  
  376. enum {
  377.     OSASyntaxTypeError            = -2741
  378. };
  379.  
  380. /* Signaled when a name or number is too long to be parsed */
  381.  
  382. enum {
  383.     OSATokenTooLong                = -2742
  384. };
  385.  
  386. /*
  387.         Signaled when a parameter is missing for a function invocation.  Note
  388.           that in some languages, this error may occur at runtime.
  389.     */
  390.  
  391. enum {
  392.     OSAMissingParameter            = errAEDescNotFound
  393. };
  394.  
  395. /*
  396.         Signaled when function is called with the wrong number of parameters,
  397.           or a parameter pattern cannot be matched.
  398.     */
  399.  
  400. enum {
  401.     OSAParameterMismatch        = errAEWrongNumberArgs
  402. };
  403.  
  404. /*
  405.         Signaled when a formal parameter, local variable, or instance variable
  406.           is specified more than once.
  407.     */
  408.  
  409. enum {
  410.     OSADuplicateParameter        = -2750
  411. };
  412.  
  413. /*
  414.         Signaled when a formal parameter, local variable, or instance variable
  415.           is specified more than once.
  416.     */
  417.  
  418. enum {
  419.     OSADuplicateProperty        = -2751
  420. };
  421.  
  422. /*
  423.         Signaled when more than one handler is defined with the same name in 
  424.           a scope where the language doesn't allow it.
  425.     */
  426.  
  427. enum {
  428.     OSADuplicateHandler            = -2752
  429. };
  430.  
  431. /* Signaled when a variable is accessed that has no value */
  432.  
  433. enum {
  434.     OSAUndefinedVariable        = -2753
  435. };
  436.  
  437. /*
  438.         Signaled when a variable is declared inconsistently in the same scope,
  439.           such as both local and global.
  440.     */
  441.  
  442. enum {
  443.     OSAInconsistentDeclarations    = -2754
  444. };
  445.  
  446. /*
  447.         Signaled when illegal control flow occurs in an application (no catcher
  448.           for throw, non-lexical loop exit, etc.).
  449.     */
  450.  
  451. enum {
  452.     OSAControlFlowError            = -2755
  453. };
  454.  
  455. /*        Component-specific static script errors:
  456.  
  457.     The range -2760 thru -2779 is reserved for component-specific parsing and
  458.     compile-time errors. (Note that error codes from different scripting
  459.     components in this range will overlap.)
  460. */
  461. /*        Dialect-specific script errors:
  462.  
  463.     The range -2780 thru -2799 is reserved for dialect specific error codes for
  464.     scripting components that support dialects. (Note that error codes from
  465.     different scripting components in this range will overlap, as well as error
  466.     codes from different dialects in the same scripting component.)
  467. */
  468. /**************************************************************************
  469.     OSA Interface Descriptions
  470. **************************************************************************
  471.     The OSA Interface is broken down into a required interface, and several
  472.     optional interfaces to support additional functionality.  A given scripting
  473.     component may choose to support only some of the optional interfaces in
  474.     addition to the basic interface.  The OSA Component Flags may be used to 
  475.     query the Component Manager to find a scripting component with a particular
  476.     capability, or determine if a particular scripting component supports a 
  477.     particular capability.
  478. **************************************************************************/
  479. /* OSA Component Flags: */
  480.  
  481. enum {
  482.     kOSASupportsCompiling        = 0x0002,
  483.     kOSASupportsGetSource        = 0x0004,
  484.     kOSASupportsAECoercion        = 0x0008,
  485.     kOSASupportsAESending        = 0x0010,
  486.     kOSASupportsRecording        = 0x0020,
  487.     kOSASupportsConvenience        = 0x0040,
  488.     kOSASupportsDialects        = 0x0080,
  489.     kOSASupportsEventHandling    = 0x0100
  490. };
  491.  
  492. /* Component Selectors: */
  493.  
  494. enum {
  495.     kOSASelectLoad                = 0x0001,
  496.     kOSASelectStore                = 0x0002,
  497.     kOSASelectExecute            = 0x0003,
  498.     kOSASelectDisplay            = 0x0004,
  499.     kOSASelectScriptError        = 0x0005,
  500.     kOSASelectDispose            = 0x0006,
  501.     kOSASelectSetScriptInfo        = 0x0007,
  502.     kOSASelectGetScriptInfo        = 0x0008,
  503.     kOSASelectSetActiveProc        = 0x0009,
  504.     kOSASelectGetActiveProc        = 0x000A
  505. };
  506.  
  507. /* Compiling: */
  508.  
  509. enum {
  510.     kOSASelectScriptingComponentName = 0x0102,
  511.     kOSASelectCompile            = 0x0103,
  512.     kOSASelectCopyID            = 0x0104
  513. };
  514.  
  515. /* GetSource: */
  516.  
  517. enum {
  518.     kOSASelectGetSource            = 0x0201
  519. };
  520.  
  521. /* AECoercion: */
  522.  
  523. enum {
  524.     kOSASelectCoerceFromDesc    = 0x0301,
  525.     kOSASelectCoerceToDesc        = 0x0302
  526. };
  527.  
  528. /* AESending: */
  529.  
  530. enum {
  531.     kOSASelectSetSendProc        = 0x0401,
  532.     kOSASelectGetSendProc        = 0x0402,
  533.     kOSASelectSetCreateProc        = 0x0403,
  534.     kOSASelectGetCreateProc        = 0x0404,
  535.     kOSASelectSetDefaultTarget    = 0x0405
  536. };
  537.  
  538. /* Recording: */
  539.  
  540. enum {
  541.     kOSASelectStartRecording    = 0x0501,
  542.     kOSASelectStopRecording        = 0x0502
  543. };
  544.  
  545. /* Convenience: */
  546.  
  547. enum {
  548.     kOSASelectLoadExecute        = 0x0601,
  549.     kOSASelectCompileExecute    = 0x0602,
  550.     kOSASelectDoScript            = 0x0603
  551. };
  552.  
  553. /* Dialects: */
  554.  
  555. enum {
  556.     kOSASelectSetCurrentDialect    = 0x0701,
  557.     kOSASelectGetCurrentDialect    = 0x0702,
  558.     kOSASelectAvailableDialects    = 0x0703,
  559.     kOSASelectGetDialectInfo    = 0x0704,
  560.     kOSASelectAvailableDialectCodeList = 0x0705
  561. };
  562.  
  563. /* Event Handling: */
  564.  
  565. enum {
  566.     kOSASelectSetResumeDispatchProc = 0x0801,
  567.     kOSASelectGetResumeDispatchProc = 0x0802,
  568.     kOSASelectExecuteEvent        = 0x0803,
  569.     kOSASelectDoEvent            = 0x0804,
  570.     kOSASelectMakeContext        = 0x0805
  571. };
  572.  
  573.  
  574. /* scripting component specific selectors are added beginning with this value  */
  575.  
  576. enum {
  577.     kOSASelectComponentSpecificStart = 0x1001
  578. };
  579.  
  580.  
  581. /*        Mode Flags:
  582.  
  583.     Warning: These should not conflict with the AESend mode flags in
  584.     AppleEvents.h, because we may want to use them as OSA mode flags too.
  585. */
  586.  
  587. /*
  588.         This mode flag may be passed to OSALoad, OSAStore or OSACompile to
  589.           instruct the scripting component to not retain the "source" of an
  590.           expression.  This will cause the OSAGetSource call to return the error
  591.           errOSASourceNotAvailable if used.  However, some scripting components
  592.           may not retain the source anyway.  This is mainly used when either space
  593.           efficiency is desired, or a script is to be "locked" so that its
  594.           implementation may not be viewed.
  595.     */
  596.  
  597. enum {
  598.     kOSAModePreventGetSource    = 0x00000001
  599. };
  600.  
  601. /*
  602.         These mode flags may be passed to OSACompile, OSAExecute, OSALoadExecute
  603.           OSACompileExecute, OSADoScript, OSAExecuteEvent, or OSADoEvent to
  604.           indicate whether or not the script may interact with the user, switch
  605.           layer or reconnect if necessary.  Any AppleEvents will be sent with the
  606.           corresponding AESend mode supplied.
  607.     */
  608.  
  609. enum {
  610.     kOSAModeNeverInteract        = kAENeverInteract,
  611.     kOSAModeCanInteract            = kAECanInteract,
  612.     kOSAModeAlwaysInteract        = kAEAlwaysInteract,
  613.     kOSAModeDontReconnect        = kAEDontReconnect
  614. };
  615.  
  616. /*
  617.         This mode flag may be passed to OSACompile, OSAExecute, OSALoadExecute
  618.           OSACompileExecute, OSADoScript, OSAExecuteEvent, or OSADoEvent to
  619.           indicate whether or not AppleEvents should be sent with the
  620.           kAECanSwitchLayer mode flag sent or not. NOTE: This flag is exactly the
  621.           opposite sense of the AppleEvent flag kAECanSwitchLayer.  This is to
  622.           provide a more convenient default, i.e. not supplying any mode
  623.           (kOSAModeNull) means to send events with kAECanSwitchLayer.  Supplying
  624.           the kOSAModeCantSwitchLayer mode flag will cause AESend to be called
  625.           without kAECanSwitchLayer.
  626.     */
  627.  
  628. enum {
  629.     kOSAModeCantSwitchLayer        = 0x00000040
  630. };
  631.  
  632. /*
  633.         This mode flag may be passed to OSACompile, OSAExecute, OSALoadExecute
  634.           OSACompileExecute, OSADoScript, OSAExecuteEvent, or OSADoEvent to
  635.           indicate whether or not AppleEvents should be sent with the kAEDontRecord
  636.           mode flag sent or not. NOTE: This flag is exactly the opposite sense of
  637.           the AppleEvent flag kAEDontRecord.  This is to provide a more convenient
  638.           default, i.e. not supplying any mode (kOSAModeNull) means to send events
  639.           with kAEDontRecord.  Supplying the kOSAModeDoRecord mode flag will 
  640.           cause AESend to be called without kAEDontRecord.
  641.     */
  642.  
  643. enum {
  644.     kOSAModeDoRecord            = 0x00001000
  645. };
  646.  
  647. /*
  648.         This is a mode flag for OSACompile that indicates that a context should
  649.           be created as the result of compilation. All handler definitions are
  650.           inserted into the new context, and variables are initialized by
  651.           evaluating their initial values in a null context (i.e. they must be
  652.           constant expressions).
  653.     */
  654.  
  655. enum {
  656.     kOSAModeCompileIntoContext    = 0x00000002
  657. };
  658.  
  659. /*
  660.         This is a mode flag for OSACompile that indicates that the previous
  661.           script ID (input to OSACompile) should be augmented with any new
  662.           definitions in the sourceData rather than replaced with a new script.
  663.           This means that the previous script ID must designate a context.
  664.           The presence of this flag causes the kOSAModeCompileIntoContext flag
  665.           to be implicitly used, causing any new definitions to be initialized
  666.           in a null context.
  667.     */
  668.  
  669. enum {
  670.     kOSAModeAugmentContext        = 0x00000004
  671. };
  672.  
  673. /*
  674.         This mode flag may be passed to OSADisplay or OSADoScript to indicate
  675.           that output only need be human-readable, not re-compilable by OSACompile.
  676.           If used, output may be arbitrarily "beautified", e.g. quotes may be left
  677.           off of string values, long lists may have elipses, etc.
  678.     */
  679.  
  680. enum {
  681.     kOSAModeDisplayForHumans    = 0x00000008
  682. };
  683.  
  684. /*
  685.         This mode flag may be passed to OSAStore in the case where the scriptID
  686.           is a context.  This causes the context to be saved, but not the context's
  687.           parent context.  When the stored context is loaded back in, the parent
  688.           will be kOSANullScript.
  689.     */
  690.  
  691. enum {
  692.     kOSAModeDontStoreParent        = 0x00010000
  693. };
  694.  
  695. /*
  696.         This mode flag may be passed to OSAExecuteEvent to cause the event to
  697.           be dispatched to the direct object of the event. The direct object (or
  698.           subject attribute if the direct object is a non-object specifier) will
  699.           be resolved, and the resulting script object will be the recipient of
  700.           the message. The context argument to OSAExecuteEvent will serve as the
  701.           root of the lookup/resolution process.
  702.     */
  703.  
  704. enum {
  705.     kOSAModeDispatchToDirectObject = 0x00020000
  706. };
  707.  
  708. /*
  709.         This mode flag may be passed to OSAExecuteEvent to indicate that
  710.           components do not have to get the data of object specifier arguments.
  711.     */
  712.  
  713. enum {
  714.     kOSAModeDontGetDataForArguments = 0x00040000
  715. };
  716.  
  717. /**************************************************************************
  718.     OSA Basic Scripting Interface
  719. **************************************************************************
  720.     Scripting components must at least support the Basic Scripting interface.
  721. **************************************************************************/
  722. /*        Loading and Storing Scripts:
  723.  
  724.     These routines allow scripts to be loaded and stored in their internal
  725.     (possibly compiled, non-text) representation.
  726. */
  727.  
  728. /* Resource type for scripts */
  729.  
  730. enum {
  731.     kOSAScriptResourceType        = kOSAGenericScriptingComponentSubtype
  732. };
  733.  
  734. /*
  735.         Default type given to OSAStore which creates "generic" loadable script
  736.           data descriptors.
  737.     */
  738.  
  739. enum {
  740.     typeOSAGenericStorage        = kOSAScriptResourceType
  741. };
  742.  
  743. EXTERN_API( OSAError )
  744. OSALoad                            (ComponentInstance         scriptingComponent,
  745.                                  const AEDesc *            scriptData,
  746.                                  long                     modeFlags,
  747.                                  OSAID *                resultingScriptID)                    FIVEWORDINLINE(0x2F3C, 0x000C, 0x0001, 0x7000, 0xA82A);
  748.  
  749. /*
  750.         OSAComponentFunctionInline(kOSASelectLoad, 12);
  751.     
  752.         Errors:
  753.             badComponentInstance        invalid scripting component instance
  754.             errOSASystemError
  755.             errOSABadStorageType:        scriptData not for this scripting component
  756.             errOSACorruptData:            data seems to be corrupt
  757.             errOSADataFormatObsolete    script data format is no longer supported
  758.             errOSADataFormatTooNew        script data format is from a newer version
  759.         
  760.         ModeFlags:
  761.             kOSAModePreventGetSource
  762.     */
  763. EXTERN_API( OSAError )
  764. OSAStore                        (ComponentInstance         scriptingComponent,
  765.                                  OSAID                     scriptID,
  766.                                  DescType                 desiredType,
  767.                                  long                     modeFlags,
  768.                                  AEDesc *                resultingScriptData)                FIVEWORDINLINE(0x2F3C, 0x0010, 0x0002, 0x7000, 0xA82A);
  769.  
  770. /*
  771.         OSAComponentFunctionInline(kOSASelectStore, 16);
  772.     
  773.         Errors:
  774.             badComponentInstance    invalid scripting component instance
  775.             errOSASystemError
  776.             errOSAInvalidID
  777.             errOSABadStorageType:    desiredType not for this scripting component
  778.         
  779.         ModeFlags:
  780.             kOSAModePreventGetSource
  781.             kOSAModeDontStoreParent
  782.     */
  783. /* Executing Scripts: */
  784. EXTERN_API( OSAError )
  785. OSAExecute                        (ComponentInstance         scriptingComponent,
  786.                                  OSAID                     compiledScriptID,
  787.                                  OSAID                     contextID,
  788.                                  long                     modeFlags,
  789.                                  OSAID *                resultingScriptValueID)                FIVEWORDINLINE(0x2F3C, 0x0010, 0x0003, 0x7000, 0xA82A);
  790.  
  791. /*
  792.         OSAComponentFunctionInline(kOSASelectExecute, 16);
  793.         This call runs a script.  The contextID represents the environment
  794.         with which global variables in the script are resolved.  The constant
  795.         kOSANullScript may be used for the contextID if the application wishes
  796.         to not deal with context directly (a default one is associated with each
  797.         scripting component instance).  The resultingScriptValueID is the 
  798.         result of evaluation, and contains a value which may be displayed using
  799.         the OSAGetSource call.  The modeFlags convey scripting component
  800.         specific information.
  801.     
  802.         Errors:
  803.             badComponentInstance    invalid scripting component instance
  804.             errOSASystemError
  805.             errOSAInvalidID
  806.             errOSAScriptError:        the executing script got an error
  807.     
  808.         ModeFlags:
  809.             kOSAModeNeverInteract
  810.             kOSAModeCanInteract
  811.             kOSAModeAlwaysInteract
  812.             kOSAModeCantSwitchLayer
  813.             kOSAModeDontReconnect
  814.             kOSAModeDoRecord
  815.     */
  816. /* Displaying results: */
  817. EXTERN_API( OSAError )
  818. OSADisplay                        (ComponentInstance         scriptingComponent,
  819.                                  OSAID                     scriptValueID,
  820.                                  DescType                 desiredType,
  821.                                  long                     modeFlags,
  822.                                  AEDesc *                resultingText)                        FIVEWORDINLINE(0x2F3C, 0x0010, 0x0004, 0x7000, 0xA82A);
  823.  
  824. /*
  825.         OSAComponentFunctionInline(kOSASelectDisplay, 16);
  826.         This call is used to convert results (script value IDs) into displayable
  827.         text. The desiredType should be at least typeChar, and modeFlags are
  828.         scripting system specific flags to control the formatting of the
  829.         resulting text. This call differs from OSAGetSource in that (1) it
  830.         always produces at least typeChar, (2) is only works on script values,
  831.         (3) it may display it's output in non-compilable form (e.g. without
  832.         string quotes, elipses inserted in long and/or circular lists, etc.) and
  833.         (4) it is required by the basic scripting interface.
  834.     
  835.         Errors:
  836.             badComponentInstance    invalid scripting component instance
  837.             errOSASystemError
  838.             errOSAInvalidID
  839.             errAECoercionFail:        desiredType not supported by scripting component
  840.     
  841.         ModeFlags:
  842.             kOSAModeDisplayForHumans
  843.     */
  844. /* Getting Error Information: */
  845. EXTERN_API( OSAError )
  846. OSAScriptError                    (ComponentInstance         scriptingComponent,
  847.                                  OSType                 selector,
  848.                                  DescType                 desiredType,
  849.                                  AEDesc *                resultingErrorDescription)            FIVEWORDINLINE(0x2F3C, 0x000C, 0x0005, 0x7000, 0xA82A);
  850.  
  851. /*
  852.         OSAComponentFunctionInline(kOSASelectScriptError, 12);
  853.         Whenever script execution returns errOSAExecutionError, this routine
  854.         may be used to get information about that error.  The selector describes
  855.         the type of information desired about the error (various selectors are
  856.         listed below).  The desiredType indicates the data type of the result
  857.         desired for that selector.
  858.     
  859.         Errors:
  860.             badComponentInstance    invalid scripting component instance
  861.             errOSASystemError
  862.             errOSABadSelector:        selector not supported by scripting component
  863.             errAECoercionFail:        desiredType not supported by scripting component
  864.     */
  865. /* OSAScriptError selectors: */
  866. /*
  867.         This selector is used to determine the error number of a script error.
  868.         These error numbers may be either system error numbers, or error numbers
  869.         that are scripting component specific.
  870.         Required desiredTypes:    
  871.               typeShortInteger
  872.     */
  873.  
  874. enum {
  875.     kOSAErrorNumber                = keyErrorNumber
  876. };
  877.  
  878. /*
  879.         This selector is used to determine the full error message associated
  880.         with the error number.  It should include the name of the application
  881.         which caused the error, as well as the specific error that occurred.
  882.         This selector is sufficient for simple error reporting (but see
  883.         kOSAErrorBriefMessage, below).
  884.         Required desiredTypes:
  885.             typeChar                    error message string
  886.     */
  887.  
  888. enum {
  889.     kOSAErrorMessage            = keyErrorString
  890. };
  891.  
  892. /*
  893.         This selector is used to determine a brief error message associated with
  894.         the error number.  This message and should not mention the name of the
  895.         application which caused the error, any partial results or offending
  896.         object (see kOSAErrorApp, kOSAErrorPartialResult and
  897.         kOSAErrorOffendingObject, below).
  898.         Required desiredTypes:
  899.               typeChar                    brief error message string
  900.     */
  901. /*  0x65727262  */
  902.  
  903. enum {
  904.     kOSAErrorBriefMessage        = FOUR_CHAR_CODE('errb')
  905. };
  906.  
  907. /*
  908.         This selector is used to determine which application actually got the
  909.         error (if it was the result of an AESend), or the current application
  910.         if ....
  911.         Required desiredTypes:
  912.               typeProcessSerialNumber        PSN of the errant application
  913.               typeChar                    name of the errant application
  914.     */
  915. /*  0x65726170  */
  916.  
  917. enum {
  918.     kOSAErrorApp                = FOUR_CHAR_CODE('erap')
  919. };
  920.  
  921. /*
  922.         This selector is used to determine any partial result returned by an 
  923.         operation. If an AESend call failed, but a partial result was returned,
  924.         then the partial result may be returned as an AEDesc.
  925.         Required desiredTypes:
  926.               typeBest                    AEDesc of any partial result
  927.     */
  928. /*  0x70746c72   */
  929.  
  930. enum {
  931.     kOSAErrorPartialResult        = FOUR_CHAR_CODE('ptlr')
  932. };
  933.  
  934. /*
  935.         This selector is used to determine any object which caused the error
  936.         that may have been indicated by an application.  The result is an 
  937.         AEDesc.
  938.         Required desiredTypes:
  939.               typeBest                    AEDesc of any offending object
  940.     */
  941. /*  0x65726f62   */
  942.  
  943. enum {
  944.     kOSAErrorOffendingObject    = FOUR_CHAR_CODE('erob')
  945. };
  946.  
  947. /*
  948.         This selector is used to determine the type expected by a coercion 
  949.         operation if a type error occurred.
  950.     */
  951. /*  0x65727274   */
  952.  
  953. enum {
  954.     kOSAErrorExpectedType        = FOUR_CHAR_CODE('errt')
  955. };
  956.  
  957. /*
  958.         This selector is used to determine the source text range (start and 
  959.         end positions) of where the error occurred.
  960.         Required desiredTypes:
  961.               typeOSAErrorRange
  962.     */
  963. /*  0x65726e67  */
  964.  
  965. enum {
  966.     kOSAErrorRange                = FOUR_CHAR_CODE('erng')
  967. };
  968.  
  969. /*
  970.         An AERecord type containing keyOSASourceStart and keyOSASourceEnd fields
  971.         of type short.
  972.     */
  973. /*  0x65726e67   */
  974.  
  975. enum {
  976.     typeOSAErrorRange            = FOUR_CHAR_CODE('erng')
  977. };
  978.  
  979. /* Field of a typeOSAErrorRange record of typeShortInteger */
  980. /*  0x73726373    */
  981.  
  982. enum {
  983.     keyOSASourceStart            = FOUR_CHAR_CODE('srcs')
  984. };
  985.  
  986. /* Field of a typeOSAErrorRange record of typeShortInteger */
  987. /*  0x73726365   */
  988.  
  989. enum {
  990.     keyOSASourceEnd                = FOUR_CHAR_CODE('srce')
  991. };
  992.  
  993. /* Disposing Script IDs: */
  994. EXTERN_API( OSAError )
  995. OSADispose                        (ComponentInstance         scriptingComponent,
  996.                                  OSAID                     scriptID)                            FIVEWORDINLINE(0x2F3C, 0x0004, 0x0006, 0x7000, 0xA82A);
  997.  
  998. /*
  999.         OSAComponentFunctionInline(kOSASelectDispose, 4);
  1000.         Disposes a script or context.
  1001.     
  1002.         Errors:
  1003.             badComponentInstance    invalid scripting component instance
  1004.             errOSASystemError
  1005.             errOSAInvalidID
  1006.     */
  1007. /* Getting and Setting Script Information: */
  1008. EXTERN_API( OSAError )
  1009. OSASetScriptInfo                (ComponentInstance         scriptingComponent,
  1010.                                  OSAID                     scriptID,
  1011.                                  OSType                 selector,
  1012.                                  long                     value)                                FIVEWORDINLINE(0x2F3C, 0x000C, 0x0007, 0x7000, 0xA82A);
  1013.  
  1014. /*
  1015.         OSAComponentFunctionInline(kOSASelectSetScriptInfo, 12);
  1016.     
  1017.         Errors:
  1018.             badComponentInstance    invalid scripting component instance
  1019.             errOSASystemError
  1020.             errOSAInvalidID
  1021.             errOSABadSelector:        selector not supported by scripting component
  1022.                                     or selector not for this scriptID
  1023.     */
  1024. EXTERN_API( OSAError )
  1025. OSAGetScriptInfo                (ComponentInstance         scriptingComponent,
  1026.                                  OSAID                     scriptID,
  1027.                                  OSType                 selector,
  1028.                                  long *                    result)                                FIVEWORDINLINE(0x2F3C, 0x000C, 0x0008, 0x7000, 0xA82A);
  1029.  
  1030. /*
  1031.         OSAComponentFunctionInline(kOSASelectGetScriptInfo, 12);
  1032.     
  1033.         Errors:
  1034.             badComponentInstance    invalid scripting component instance
  1035.             errOSASystemError
  1036.             errOSAInvalidID
  1037.             errOSABadSelector:        selector not supported by scripting component
  1038.                                     or selector not for this scriptID
  1039.     */
  1040. /* Manipulating the ActiveProc:
  1041.  
  1042.     Scripting systems will supply default values for these procedures if they
  1043.     are not set by the client:
  1044. */
  1045. typedef CALLBACK_API( OSErr , OSAActiveProcPtr )(long refCon);
  1046. typedef STACK_UPP_TYPE(OSAActiveProcPtr)                         OSAActiveUPP;
  1047. enum { uppOSAActiveProcInfo = 0x000000E0 };                     /* pascal 2_bytes Func(4_bytes) */
  1048. #define NewOSAActiveProc(userRoutine)                             (OSAActiveUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppOSAActiveProcInfo, GetCurrentArchitecture())
  1049. #define CallOSAActiveProc(userRoutine, refCon)                     CALL_ONE_PARAMETER_UPP((userRoutine), uppOSAActiveProcInfo, (refCon))
  1050. EXTERN_API( OSAError )
  1051. OSASetActiveProc                (ComponentInstance         scriptingComponent,
  1052.                                  OSAActiveUPP             activeProc,
  1053.                                  long                     refCon)                                FIVEWORDINLINE(0x2F3C, 0x0008, 0x0009, 0x7000, 0xA82A);
  1054.  
  1055. /*
  1056.         OSAComponentFunctionInline(kOSASelectSetActiveProc, 8);
  1057.         If activeProc is nil, the default activeProc is used.
  1058.     
  1059.         Errors:
  1060.             badComponentInstance    invalid scripting component instance
  1061.             errOSASystemError
  1062.     */
  1063. EXTERN_API( OSAError )
  1064. OSAGetActiveProc                (ComponentInstance         scriptingComponent,
  1065.                                  OSAActiveUPP *            activeProc,
  1066.                                  long *                    refCon)                                FIVEWORDINLINE(0x2F3C, 0x0008, 0x000A, 0x7000, 0xA82A);
  1067.  
  1068. /*
  1069.         OSAComponentFunctionInline(kOSASelectGetActiveProc, 8);
  1070.     
  1071.         Errors:
  1072.             badComponentInstance    invalid scripting component instance
  1073.             errOSASystemError
  1074.     */
  1075. /**************************************************************************
  1076.     OSA Optional Compiling Interface
  1077. **************************************************************************
  1078.     Scripting components that support the Compiling interface have the 
  1079.     kOSASupportsCompiling bit set in it's ComponentDescription.
  1080. **************************************************************************/
  1081. EXTERN_API( OSAError )
  1082. OSAScriptingComponentName        (ComponentInstance         scriptingComponent,
  1083.                                  AEDesc *                resultingScriptingComponentName)    FIVEWORDINLINE(0x2F3C, 0x0004, 0x0102, 0x7000, 0xA82A);
  1084.  
  1085. /*
  1086.         OSAComponentFunctionInline(kOSASelectScriptingComponentName, 4);
  1087.         Given a scripting component, this routine returns the name of that
  1088.         scripting component in a type that is coercable to text (typeChar).
  1089.         The generic scripting component returns the name of the default
  1090.         scripting component.  This name should be sufficient to convey to the
  1091.         user the kind of script (syntax) he is expected to write.
  1092.     
  1093.         Errors:
  1094.             badComponentInstance    invalid scripting component instance
  1095.             errOSASystemError
  1096.     */
  1097. EXTERN_API( OSAError )
  1098. OSACompile                        (ComponentInstance         scriptingComponent,
  1099.                                  const AEDesc *            sourceData,
  1100.                                  long                     modeFlags,
  1101.                                  OSAID *                previousAndResultingScriptID)        FIVEWORDINLINE(0x2F3C, 0x000C, 0x0103, 0x7000, 0xA82A);
  1102.  
  1103. /*
  1104.         OSAComponentFunctionInline(kOSASelectCompile, 12);
  1105.         Coerces input desc (possibly text) into a script's internal format.
  1106.         Once compiled, the script is ready to run.  The modeFlags convey
  1107.         scripting component specific information.  The previous script ID
  1108.         (result parameter) is made to refer to the newly compiled script,
  1109.         unless it was originally kOSANullScript.  In this case a new script
  1110.         ID is created and used.
  1111.     
  1112.         Errors:
  1113.             badComponentInstance    invalid scripting component instance
  1114.             errOSASystemError
  1115.             errAECoercionFail:        sourceData is not compilable
  1116.             errOSAScriptError:        sourceData was a bad script (syntax error)
  1117.             errOSAInvalidID:        previousAndResultingCompiledScriptID was not
  1118.                                     valid on input
  1119.     
  1120.         ModeFlags:
  1121.             kOSAModePreventGetSource
  1122.             kOSAModeCompileIntoContext
  1123.             kOSAModeAugmentContext
  1124.             kOSAModeNeverInteract
  1125.             kOSAModeCanInteract
  1126.             kOSAModeAlwaysInteract
  1127.             kOSAModeCantSwitchLayer
  1128.             kOSAModeDontReconnect
  1129.             kOSAModeDoRecord
  1130.     */
  1131. EXTERN_API( OSAError )
  1132. OSACopyID                        (ComponentInstance         scriptingComponent,
  1133.                                  OSAID                     fromID,
  1134.                                  OSAID *                toID)                                FIVEWORDINLINE(0x2F3C, 0x0008, 0x0104, 0x7000, 0xA82A);
  1135.  
  1136. /*
  1137.         OSAComponentFunctionInline(kOSASelectCopyID, 8);
  1138.         If toID is a reference to kOSANullScript then it is updated to have a
  1139.         new scriptID value.  This call can be used to perform undo or revert
  1140.         operations on scripts. 
  1141.     
  1142.         Errors:
  1143.             badComponentInstance    invalid scripting component instance
  1144.             errOSASystemError
  1145.             errOSAInvalidID
  1146.     */
  1147. /**************************************************************************
  1148.     OSA Optional GetSource Interface
  1149. **************************************************************************
  1150.     Scripting components that support the GetSource interface have the 
  1151.     kOSASupportsGetSource bit set in it's ComponentDescription.
  1152. **************************************************************************/
  1153. EXTERN_API( OSAError )
  1154. OSAGetSource                    (ComponentInstance         scriptingComponent,
  1155.                                  OSAID                     scriptID,
  1156.                                  DescType                 desiredType,
  1157.                                  AEDesc *                resultingSourceData)                FIVEWORDINLINE(0x2F3C, 0x000C, 0x0201, 0x7000, 0xA82A);
  1158.  
  1159. /*
  1160.         OSAComponentFunctionInline(kOSASelectGetSource, 12);
  1161.         This routine causes a compiled script to be output in a form (possibly
  1162.         text) such that it is suitable to be passed back to OSACompile.
  1163.  
  1164.         Errors:
  1165.             badComponentInstance    invalid scripting component instance
  1166.             errOSASystemError
  1167.             errOSAInvalidID
  1168.             errOSASourceNotAvailable    can't get source for this scriptID
  1169.     */
  1170. /**************************************************************************
  1171.     OSA Optional AECoercion Interface
  1172. **************************************************************************
  1173.     Scripting components that support the AECoercion interface have the 
  1174.     kOSASupportsAECoercion bit set in it's ComponentDescription.
  1175. **************************************************************************/
  1176. EXTERN_API( OSAError )
  1177. OSACoerceFromDesc                (ComponentInstance         scriptingComponent,
  1178.                                  const AEDesc *            scriptData,
  1179.                                  long                     modeFlags,
  1180.                                  OSAID *                resultingScriptID)                    FIVEWORDINLINE(0x2F3C, 0x000C, 0x0301, 0x7000, 0xA82A);
  1181.  
  1182. /*
  1183.         OSAComponentFunctionInline(kOSASelectCoerceFromDesc, 12);
  1184.         This routine causes script data to be coerced into a script value.
  1185.         If the scriptData is an AppleEvent, then the resultingScriptID is a
  1186.         compiled script ID (mode flags for OSACompile may be used in this case).
  1187.         Other scriptData descriptors create script value IDs.
  1188.     
  1189.         Errors:
  1190.             badComponentInstance    invalid scripting component instance
  1191.             errOSASystemError
  1192.     
  1193.         ModeFlags:
  1194.             kOSAModePreventGetSource
  1195.             kOSAModeCompileIntoContext
  1196.             kOSAModeNeverInteract
  1197.             kOSAModeCanInteract
  1198.             kOSAModeAlwaysInteract
  1199.             kOSAModeCantSwitchLayer
  1200.             kOSAModeDontReconnect
  1201.             kOSAModeDoRecord
  1202.     */
  1203. EXTERN_API( OSAError )
  1204. OSACoerceToDesc                    (ComponentInstance         scriptingComponent,
  1205.                                  OSAID                     scriptID,
  1206.                                  DescType                 desiredType,
  1207.                                  long                     modeFlags,
  1208.                                  AEDesc *                result)                                FIVEWORDINLINE(0x2F3C, 0x0010, 0x0302, 0x7000, 0xA82A);
  1209.  
  1210. /*
  1211.         OSAComponentFunctionInline(kOSASelectCoerceToDesc, 16);
  1212.         This routine causes a script value to be coerced into any desired form.
  1213.         If the scriptID denotes a compiled script, then it may be coerced to 
  1214.         typeAppleEvent.
  1215.     
  1216.         Errors:
  1217.             badComponentInstance    invalid scripting component instance
  1218.             errOSASystemError
  1219.             errOSAInvalidID
  1220.     */
  1221. /**************************************************************************
  1222.     OSA Optional AESending Interface
  1223. **************************************************************************
  1224.     Scripting components that support the AESending interface have the 
  1225.     kOSASupportsAESending bit set in it's ComponentDescription.
  1226. **************************************************************************/
  1227. /*
  1228.     Scripting systems will supply default values for these procedures if they
  1229.     are not set by the client:
  1230. */
  1231. EXTERN_API( OSAError )
  1232. OSASetSendProc                    (ComponentInstance         scriptingComponent,
  1233.                                  OSASendUPP             sendProc,
  1234.                                  long                     refCon)                                FIVEWORDINLINE(0x2F3C, 0x0008, 0x0401, 0x7000, 0xA82A);
  1235.  
  1236. /*
  1237.         OSAComponentFunctionInline(kOSASelectSetSendProc, 8);
  1238.         If sendProc is nil, the default sendProc is used.
  1239.     
  1240.         Errors:
  1241.             badComponentInstance    invalid scripting component instance
  1242.             errOSASystemError
  1243.     */
  1244. EXTERN_API( OSAError )
  1245. OSAGetSendProc                    (ComponentInstance         scriptingComponent,
  1246.                                  OSASendUPP *            sendProc,
  1247.                                  long *                    refCon)                                FIVEWORDINLINE(0x2F3C, 0x0008, 0x0402, 0x7000, 0xA82A);
  1248.  
  1249. /*
  1250.         OSAComponentFunctionInline(kOSASelectGetSendProc, 8);
  1251.     
  1252.         Errors:
  1253.             badComponentInstance    invalid scripting component instance
  1254.             errOSASystemError
  1255.     */
  1256. EXTERN_API( OSAError )
  1257. OSASetCreateProc                (ComponentInstance         scriptingComponent,
  1258.                                  OSACreateAppleEventUPP  createProc,
  1259.                                  long                     refCon)                                FIVEWORDINLINE(0x2F3C, 0x0008, 0x0403, 0x7000, 0xA82A);
  1260.  
  1261. /*
  1262.         OSAComponentFunctionInline(kOSASelectSetCreateProc, 8);
  1263.         If createProc is nil, the default createProc is used.
  1264.     
  1265.         Errors:
  1266.             badComponentInstance    invalid scripting component instance
  1267.             errOSASystemError
  1268.     */
  1269. EXTERN_API( OSAError )
  1270. OSAGetCreateProc                (ComponentInstance         scriptingComponent,
  1271.                                  OSACreateAppleEventUPP * createProc,
  1272.                                  long *                    refCon)                                FIVEWORDINLINE(0x2F3C, 0x0008, 0x0404, 0x7000, 0xA82A);
  1273.  
  1274. /*
  1275.         OSAComponentFunctionInline(kOSASelectGetCreateProc, 8);
  1276.     
  1277.         Errors:
  1278.             badComponentInstance    invalid scripting component instance
  1279.             errOSASystemError
  1280.     */
  1281. EXTERN_API( OSAError )
  1282. OSASetDefaultTarget                (ComponentInstance         scriptingComponent,
  1283.                                  const AEAddressDesc *    target)                                FIVEWORDINLINE(0x2F3C, 0x0004, 0x0405, 0x7000, 0xA82A);
  1284.  
  1285. /*
  1286.         OSAComponentFunctionInline(kOSASelectSetDefaultTarget, 4);
  1287.         This routine sets the default target application for AE sending.
  1288.         It also establishes the default target from which terminologies come.
  1289.         It is effectively like having an AppleScript "tell" statement around
  1290.         the entire program.  If this routine is not called, or if the target 
  1291.         is a null AEDesc, then the current application is the default target.
  1292.     
  1293.         Errors:
  1294.             badComponentInstance    invalid scripting component instance
  1295.             errOSASystemError
  1296.     */
  1297. /**************************************************************************
  1298.     OSA Optional Recording Interface
  1299. **************************************************************************
  1300.     Scripting components that support the Recording interface have the 
  1301.     kOSASupportsRecording bit set in it's ComponentDescription.
  1302. **************************************************************************/
  1303. EXTERN_API( OSAError )
  1304. OSAStartRecording                (ComponentInstance         scriptingComponent,
  1305.                                  OSAID *                compiledScriptToModifyID)            FIVEWORDINLINE(0x2F3C, 0x0004, 0x0501, 0x7000, 0xA82A);
  1306.  
  1307. /*
  1308.         OSAComponentFunctionInline(kOSASelectStartRecording, 4);
  1309.         Starts recording.  If compiledScriptToModifyID is kOSANullScript, a
  1310.         new script ID is created and returned.  If the current application has
  1311.         a handler for the kOSARecordedText event, then kOSARecordedText events
  1312.         are sent to the application containing the text of each AppleEvent 
  1313.         recorded.
  1314.     
  1315.         Errors:
  1316.             badComponentInstance    invalid scripting component instance
  1317.             errOSASystemError
  1318.             errOSAInvalidID
  1319.             errOSARecordingIsAlreadyOn
  1320.     */
  1321. EXTERN_API( OSAError )
  1322. OSAStopRecording                (ComponentInstance         scriptingComponent,
  1323.                                  OSAID                     compiledScriptID)                    FIVEWORDINLINE(0x2F3C, 0x0004, 0x0502, 0x7000, 0xA82A);
  1324.  
  1325. /*
  1326.         OSAComponentFunctionInline(kOSASelectStopRecording, 4);
  1327.         If compiledScriptID is not being recorded into or recording is not
  1328.         currently on, no error is returned.
  1329.     
  1330.         Errors:
  1331.             badComponentInstance    invalid scripting component instance
  1332.             errOSASystemError
  1333.             errOSAInvalidID
  1334.     */
  1335. /**************************************************************************
  1336.     OSA Optional Convenience Interface
  1337. **************************************************************************
  1338.     Scripting components that support the Convenience interface have the 
  1339.     kOSASupportsConvenience bit set in it's ComponentDescription.
  1340. **************************************************************************/
  1341. EXTERN_API( OSAError )
  1342. OSALoadExecute                    (ComponentInstance         scriptingComponent,
  1343.                                  const AEDesc *            scriptData,
  1344.                                  OSAID                     contextID,
  1345.                                  long                     modeFlags,
  1346.                                  OSAID *                resultingScriptValueID)                FIVEWORDINLINE(0x2F3C, 0x0010, 0x0601, 0x7000, 0xA82A);
  1347.  
  1348. /*
  1349.         OSAComponentFunctionInline(kOSASelectLoadExecute, 16);
  1350.         This routine is effectively equivalent to calling OSALoad followed by
  1351.         OSAExecute.  After execution, the compiled source is disposed.  Only the
  1352.         resulting value ID is retained.
  1353.     
  1354.         Errors:
  1355.             badComponentInstance        invalid scripting component instance
  1356.             errOSASystemError
  1357.             errOSABadStorageType:        scriptData not for this scripting component
  1358.             errOSACorruptData:            data seems to be corrupt
  1359.             errOSADataFormatObsolete    script data format is no longer supported
  1360.             errOSADataFormatTooNew        script data format is from a newer version
  1361.             errOSAInvalidID
  1362.             errOSAScriptError:            the executing script got an error
  1363.     
  1364.         ModeFlags:
  1365.             kOSAModeNeverInteract
  1366.             kOSAModeCanInteract
  1367.             kOSAModeAlwaysInteract
  1368.             kOSAModeCantSwitchLayer
  1369.             kOSAModeDontReconnect
  1370.             kOSAModeDoRecord
  1371.     */
  1372. EXTERN_API( OSAError )
  1373. OSACompileExecute                (ComponentInstance         scriptingComponent,
  1374.                                  const AEDesc *            sourceData,
  1375.                                  OSAID                     contextID,
  1376.                                  long                     modeFlags,
  1377.                                  OSAID *                resultingScriptValueID)                FIVEWORDINLINE(0x2F3C, 0x0010, 0x0602, 0x7000, 0xA82A);
  1378.  
  1379. /*
  1380.         OSAComponentFunctionInline(kOSASelectCompileExecute, 16);
  1381.         This routine is effectively equivalent to calling OSACompile followed by
  1382.         OSAExecute.  After execution, the compiled source is disposed.  Only the
  1383.         resulting value ID is retained.
  1384.     
  1385.         Errors:
  1386.             badComponentInstance    invalid scripting component instance
  1387.             errOSASystemError
  1388.             errAECoercionFail:        sourceData is not compilable
  1389.             errOSAScriptError:        sourceData was a bad script (syntax error)
  1390.             errOSAInvalidID:        previousAndResultingCompiledScriptID was not
  1391.                                     valid on input
  1392.             errOSAScriptError:        the executing script got an error
  1393.     
  1394.         ModeFlags:
  1395.             kOSAModeNeverInteract
  1396.             kOSAModeCanInteract
  1397.             kOSAModeAlwaysInteract
  1398.             kOSAModeCantSwitchLayer
  1399.             kOSAModeDontReconnect
  1400.             kOSAModeDoRecord
  1401.     */
  1402. EXTERN_API( OSAError )
  1403. OSADoScript                        (ComponentInstance         scriptingComponent,
  1404.                                  const AEDesc *            sourceData,
  1405.                                  OSAID                     contextID,
  1406.                                  DescType                 desiredType,
  1407.                                  long                     modeFlags,
  1408.                                  AEDesc *                resultingText)                        FIVEWORDINLINE(0x2F3C, 0x0014, 0x0603, 0x7000, 0xA82A);
  1409.  
  1410. /*
  1411.         OSAComponentFunctionInline(kOSASelectDoScript, 20);
  1412.         This routine is effectively equivalent to calling OSACompile followed by
  1413.         OSAExecute and then OSADisplay.  After execution, the compiled source
  1414.         and the resulting value are is disposed.  Only the resultingText
  1415.         descriptor is retained.  If a script error occur during processing, the 
  1416.         resultingText gets the error message of the error, and errOSAScriptError
  1417.         is returned.  OSAScriptError may still be used to extract more 
  1418.         information about the particular error.
  1419.     
  1420.         Errors:
  1421.             badComponentInstance    invalid scripting component instance
  1422.             errOSASystemError
  1423.             errAECoercionFail:        sourceData is not compilable or 
  1424.                                     desiredType not supported by scripting component
  1425.             errOSAScriptError:        sourceData was a bad script (syntax error)
  1426.             errOSAInvalidID:        previousAndResultingCompiledScriptID was not
  1427.                                     valid on input
  1428.             errOSAScriptError:        the executing script got an error
  1429.     
  1430.         ModeFlags:
  1431.             kOSAModeNeverInteract
  1432.             kOSAModeCanInteract
  1433.             kOSAModeAlwaysInteract
  1434.             kOSAModeCantSwitchLayer
  1435.             kOSAModeDontReconnect
  1436.             kOSAModeDoRecord
  1437.             kOSAModeDisplayForHumans
  1438.     */
  1439. /**************************************************************************
  1440.     OSA Optional Dialects Interface
  1441. **************************************************************************
  1442.     Scripting components that support the Dialects interface have the 
  1443.     kOSASupportsDialects bit set in it's ComponentDescription.
  1444. **************************************************************************/
  1445. /*
  1446.     These calls allows an scripting component that supports different dialects
  1447.     to dynamically switch between those dialects.  Although this interface is
  1448.     specified, the particular dialect codes are scripting component dependent.
  1449. */
  1450. EXTERN_API( OSAError )
  1451. OSASetCurrentDialect            (ComponentInstance         scriptingComponent,
  1452.                                  short                     dialectCode)                        FIVEWORDINLINE(0x2F3C, 0x0002, 0x0701, 0x7000, 0xA82A);
  1453.  
  1454. /*
  1455.         OSAComponentFunctionInline(kOSASelectSetCurrentDialect, 2);
  1456.     
  1457.         Errors:
  1458.             badComponentInstance    invalid scripting component instance
  1459.             errOSASystemError
  1460.             errOSANoSuchDialect:    invalid dialectCode
  1461.     */
  1462. EXTERN_API( OSAError )
  1463. OSAGetCurrentDialect            (ComponentInstance         scriptingComponent,
  1464.                                  short *                resultingDialectCode)                FIVEWORDINLINE(0x2F3C, 0x0004, 0x0702, 0x7000, 0xA82A);
  1465.  
  1466. /*
  1467.         OSAComponentFunctionInline(kOSASelectGetCurrentDialect, 4);
  1468.     
  1469.         Errors:
  1470.             badComponentInstance    invalid scripting component instance
  1471.             errOSASystemError
  1472.     */
  1473. EXTERN_API( OSAError )
  1474. OSAAvailableDialects            (ComponentInstance         scriptingComponent,
  1475.                                  AEDesc *                resultingDialectInfoList)            FIVEWORDINLINE(0x2F3C, 0x0004, 0x0703, 0x7000, 0xA82A);
  1476.  
  1477. /*
  1478.         OSAComponentFunctionInline(kOSASelectAvailableDialects, 4);
  1479.         This call return an AEList containing information about each of the
  1480.         currently available dialects of a scripting component.  Each item
  1481.         is an AERecord of typeOSADialectInfo that contains at least the fields
  1482.         keyOSADialectName, keyOSADialectCode, KeyOSADialectLangCode and 
  1483.         keyOSADialectScriptCode.
  1484.     
  1485.         Errors:
  1486.             badComponentInstance    invalid scripting component instance
  1487.             errOSASystemError
  1488.     */
  1489. EXTERN_API( OSAError )
  1490. OSAGetDialectInfo                (ComponentInstance         scriptingComponent,
  1491.                                  short                     dialectCode,
  1492.                                  OSType                 selector,
  1493.                                  AEDesc *                resultingDialectInfo)                FIVEWORDINLINE(0x2F3C, 0x000A, 0x0704, 0x7000, 0xA82A);
  1494.  
  1495. /*
  1496.         OSAComponentFunctionInline(kOSASelectGetDialectInfo, 10);
  1497.         This call gives information about the specified dialect of a scripting
  1498.         component. It returns an AEDesc whose type depends on the selector 
  1499.         specified. Available selectors are the same as the field keys for a
  1500.         dialect info record. The type of AEDesc returned is the same as the 
  1501.         type of the field that has same key as the selector.
  1502.     
  1503.         Errors:
  1504.             badComponentInstance    invalid scripting component instance
  1505.             errOSASystemError
  1506.              errOSABadSelector
  1507.             errOSANoSuchDialect:    invalid dialectCode
  1508.     */
  1509. EXTERN_API( OSAError )
  1510. OSAAvailableDialectCodeList        (ComponentInstance         scriptingComponent,
  1511.                                  AEDesc *                resultingDialectCodeList)            FIVEWORDINLINE(0x2F3C, 0x0004, 0x0705, 0x7000, 0xA82A);
  1512.  
  1513. /*
  1514.         OSAComponentFunctionInline(kOSASelectAvailableDialectCodeList, 4);
  1515.         This is alternative to OSAGetAvailableDialectCodeList. Use this call
  1516.         and  OSAGetDialectInfo to get information on dialects.
  1517.         This call return an AEList containing dialect code for each of the
  1518.         currently available dialects of a scripting component. Each dialect
  1519.         code is a short integer of type typeShortInteger.
  1520.     
  1521.         Errors:
  1522.             badComponentInstance    invalid scripting component instance
  1523.             errOSASystemError
  1524.  
  1525.         Type of a dialect info record containing at least keyOSADialectName
  1526.         and keyOSADialectCode fields.
  1527.  
  1528.         keys for dialect info record, also used as selectors to OSAGetDialectInfo.
  1529.  
  1530.         Field of a typeOSADialectInfo record of typeChar.
  1531.         Field of a typeOSADialectInfo record of typeShortInteger.
  1532.         Field of a typeOSADialectInfo record of typeShortInteger.
  1533.         Field of a typeOSADialectInfo record of typeShortInteger.
  1534.     */
  1535. /**************************************************************************
  1536.     OSA Optional Event Handling Interface
  1537. **************************************************************************
  1538.     Scripting components that support the Event Handling interface have the 
  1539.     kOSASupportsEventHandling bit set in it's ComponentDescription.
  1540. **************************************************************************/
  1541. EXTERN_API( OSAError )
  1542. OSASetResumeDispatchProc        (ComponentInstance         scriptingComponent,
  1543.                                  AEEventHandlerUPP         resumeDispatchProc,
  1544.                                  long                     refCon)                                FIVEWORDINLINE(0x2F3C, 0x0008, 0x0801, 0x7000, 0xA82A);
  1545.  
  1546. /*
  1547.         OSAComponentFunctionInline(kOSASelectSetResumeDispatchProc, 8);
  1548.         This function is used to set the ResumeDispatchProc that will be used
  1549.         by OSAExecuteEvent and OSADoEvent if either no event handler can be
  1550.         found in the context, or the context event hander "continues" control
  1551.         onward. The two constants kOSAUseStandardDispatch and kOSANoDispatch
  1552.         may also be passed to this routine indicating that the handler registered
  1553.         in the application with AEInstallEventHandler should be used, or no
  1554.         dispatch should occur, respectively.
  1555.     
  1556.         Errors:
  1557.             badComponentInstance    invalid scripting component instance
  1558.             errOSASystemError
  1559.     */
  1560.  
  1561. enum {
  1562.     kOSAUseStandardDispatch        = kAEUseStandardDispatch
  1563. };
  1564.  
  1565. /*
  1566.         Special ResumeDispatchProc constant which may be passed to 
  1567.         OSASetResumeDispatchProc indicating that the handler registered
  1568.         in the application with AEInstallEventHandler should be used.
  1569.         
  1570.         NOTE:    Had to remove the cast (AEEventHandlerUPP).  The C compiler
  1571.                 doesn't allow pointer types to be assigned to an enum.  All
  1572.                 constants must be assigned as enums to translate properly to
  1573.                 Pascal.
  1574.     */
  1575.  
  1576. enum {
  1577.     kOSANoDispatch                = kAENoDispatch
  1578. };
  1579.  
  1580. /*
  1581.         Special ResumeDispatchProc constant which may be passed to 
  1582.         OSASetResumeDispatchProc indicating that no dispatch should occur.
  1583.         
  1584.         NOTE:    Had to remove the cast (AEEventHandlerUPP).  The C compiler
  1585.                 doesn't allow pointer types to be assigned to an enum.  All
  1586.                 constants must be assigned as enums to translate properly to
  1587.                 Pascal.
  1588.     */
  1589.  
  1590. enum {
  1591.     kOSADontUsePhac                = 0x0001
  1592. };
  1593.  
  1594. /*
  1595.         Special refCon constant that may be given to OSASetResumeDispatchProc
  1596.         only when kOSAUseStandardDispatch is used as the ResumeDispatchProc.
  1597.         This causes the standard dispatch to be performed, except the phac
  1598.         handler is not called.  This is useful during tinkerability, when
  1599.         the phac handler is used to lookup a context associated with an event's 
  1600.         direct parameter, and call OSAExecuteEvent or OSADoEvent.  Failure to
  1601.         bypass the phac handler would result in an infinite loop.
  1602.     */
  1603. EXTERN_API( OSAError )
  1604. OSAGetResumeDispatchProc        (ComponentInstance         scriptingComponent,
  1605.                                  AEEventHandlerUPP *    resumeDispatchProc,
  1606.                                  long *                    refCon)                                FIVEWORDINLINE(0x2F3C, 0x0008, 0x0802, 0x7000, 0xA82A);
  1607.  
  1608. /*
  1609.         OSAComponentFunctionInline(kOSASelectGetResumeDispatchProc, 8);
  1610.         Returns the registered ResumeDispatchProc.  If no ResumeDispatchProc has
  1611.         been registered, then kOSAUseStandardDispatch (the default) is returned.
  1612.     
  1613.         Errors:
  1614.             badComponentInstance    invalid scripting component instance
  1615.             errOSASystemError
  1616.     */
  1617. EXTERN_API( OSAError )
  1618. OSAExecuteEvent                    (ComponentInstance         scriptingComponent,
  1619.                                  const AppleEvent *        theAppleEvent,
  1620.                                  OSAID                     contextID,
  1621.                                  long                     modeFlags,
  1622.                                  OSAID *                resultingScriptValueID)                FIVEWORDINLINE(0x2F3C, 0x0010, 0x0803, 0x7000, 0xA82A);
  1623.  
  1624. /*
  1625.         OSAComponentFunctionInline(kOSASelectExecuteEvent, 16);
  1626.         This call is similar to OSAExecute except the initial command to
  1627.         execute comes in the form of an AppleEvent.  If the contextID
  1628.         defines any event handlers for that event, they are used to process
  1629.         the event.  If no event handler can be found in the context
  1630.         errAEEventNotHandled is returned.  If an event handler is found and
  1631.         the hander "continues" control onward, the ResumeDispatchProc
  1632.         (registered with OSASetResumeDispatchProc, above) is called given the
  1633.         AppleEvent.  The result is returned as a scriptValueID.
  1634.     
  1635.         Errors:
  1636.             badComponentInstance    invalid scripting component instance
  1637.             errOSASystemError
  1638.             errOSAInvalidID
  1639.             errOSAScriptError:        the executing script got an error
  1640.             errAEEventNotHandled:    no handler for event in contextID
  1641.     
  1642.         ModeFlags:
  1643.             kOSAModeNeverInteract
  1644.             kOSAModeCanInteract
  1645.             kOSAModeAlwaysInteract
  1646.             kOSAModeCantSwitchLayer
  1647.             kOSAModeDontReconnect
  1648.             kOSAModeDoRecord
  1649.     */
  1650. EXTERN_API( OSAError )
  1651. OSADoEvent                        (ComponentInstance         scriptingComponent,
  1652.                                  const AppleEvent *        theAppleEvent,
  1653.                                  OSAID                     contextID,
  1654.                                  long                     modeFlags,
  1655.                                  AppleEvent *            reply)                                FIVEWORDINLINE(0x2F3C, 0x0010, 0x0804, 0x7000, 0xA82A);
  1656.  
  1657. /*
  1658.         OSAComponentFunctionInline(kOSASelectDoEvent, 16);
  1659.         This call is similar to OSADoScript except the initial command to
  1660.         execute comes in the form of an AppleEvent, and the result is an 
  1661.         AppleEvent reply record.  If the contextID defines any event handlers
  1662.         for that event, they are used to process the event.  If no event handler
  1663.         can be found in the context errAEEventNotHandled is returned.  If an
  1664.         event handler is found and the hander "continues" control onward, the
  1665.         ResumeDispatchProc (registered with OSASetResumeDispatchProc, above) is
  1666.         called given the AppleEvent.  The result is returned in the form of an
  1667.         AppleEvent reply descriptor. If at any time the script gets an error, or
  1668.         if the ResumeDispatchProc returns a reply event indicating an error,
  1669.         then the OSADoEvent call itself returns an error reply (i.e. OSADoEvent
  1670.         should never return errOSAScriptError).  Any error result returned by
  1671.         the ResumeDispatchProc will be returned by OSADoEvent.
  1672.     
  1673.         Errors:
  1674.             badComponentInstance    invalid scripting component instance
  1675.             errOSASystemError
  1676.             errOSAInvalidID
  1677.             errAEEventNotHandled:    no handler for event in contextID
  1678.     
  1679.         ModeFlags:
  1680.             kOSAModeNeverInteract
  1681.             kOSAModeCanInteract
  1682.             kOSAModeAlwaysInteract
  1683.             kOSAModeCantSwitchLayer
  1684.             kOSAModeDontReconnect
  1685.             kOSAModeDoRecord
  1686.     */
  1687. EXTERN_API( OSAError )
  1688. OSAMakeContext                    (ComponentInstance         scriptingComponent,
  1689.                                  const AEDesc *            contextName,
  1690.                                  OSAID                     parentContext,
  1691.                                  OSAID *                resultingContextID)                    FIVEWORDINLINE(0x2F3C, 0x000C, 0x0805, 0x7000, 0xA82A);
  1692.  
  1693. /*
  1694.         OSAComponentFunctionInline(kOSASelectMakeContext, 12);
  1695.         Makes a new empty context which may be passed to OSAExecute or 
  1696.         OSAExecuteEvent.  If contextName is typeNull, an unnamed context is
  1697.         created. If parentContext is kOSANullScript then the resulting context
  1698.         does not inherit bindings from any other context.
  1699.     
  1700.         Errors:
  1701.             badComponentInstance    invalid scripting component instance
  1702.             errOSASystemError
  1703.             errOSAInvalidID
  1704.             errAECoercionFail:        contextName is invalid
  1705.     */
  1706.  
  1707.  
  1708. #if PRAGMA_STRUCT_ALIGN
  1709.     #pragma options align=reset
  1710. #elif PRAGMA_STRUCT_PACKPUSH
  1711.     #pragma pack(pop)
  1712. #elif PRAGMA_STRUCT_PACK
  1713.     #pragma pack()
  1714. #endif
  1715.  
  1716. #ifdef PRAGMA_IMPORT_OFF
  1717. #pragma import off
  1718. #elif PRAGMA_IMPORT
  1719. #pragma import reset
  1720. #endif
  1721.  
  1722. #ifdef __cplusplus
  1723. }
  1724. #endif
  1725.  
  1726. #endif /* __OSA__ */
  1727.  
  1728.